Maintaining Cross References in Manuscripts

Authors face the tedious bookkeeping problem of maintaining the consistency of references to figures, citations, and other numbered entities in successive drafts of a manuscript. If a figure is added to or deleted from the manuscript, the numbers of all subsequent figures must be adjusted, along with the references to these figures. In this note, we show how the UNIX commands grep, awk, and sed can be used to create a simple and flexible reference assembler that automatically maintains the consistency of cross references in manuscripts. 1. A REFERENCE ASSEMBLER First, prepare a source text for the manuscript in which each reference is symbolic, such as ‘‘Fig. _Output_’’ or ‘‘Page _Section2_’’, rather than an explicit numeric designation, such as ‘‘Fig. 3’’ or ‘‘Page 3’’. Following Scribe [8], the name of a numbered entity will be called a tag, and a symbolic page number a page label. Tags represent numbers that are independent of the layout of a manuscript: The number associated with a tag depends on how many other tag definitions precede it in the source text, and can be deduced by looking at the source text alone. Page numbers, on the other hand, depend on the final layout of the text. Section 4 describes a mechanism for handling page labels using the troff text-formatter. In the source text, define each tag by a line of the form .@tag countervariable tagname In a tag definition, @tag is a distinctive keyword, countervariable is an identifier for an integer variable, and tagname is a string used as a tag. The . in the first position of the definition indicates that the line is not part of the actual text of the manuscript. Tag definitions and references can appear anywhere in the source text, but the definitions will be numbered in the order in which they appear. The initial value of a counter variable is zero. Whenever a new tag definition is encountered, the underlying counter variable is incremented and the incremented value of this counter variable is associated with the new tag name. We can create as many different classes of symbolic references as we wish by using a distinct counter variable for each class. In this way, citations, figures, examples, sections, footnotes, and the like can have their own sequence numbers. Example 1. Figure 1 shows the contents of a file source containing the text of a short manuscript. Lines 3, 6, 8, and 11 contain the tags _Alice_ and _Huckleberry_. Lines 7 and 10 contain the corresponding tag definitions .@tag CITE _Alice_ .@tag CITE _Huckleberry_ using the counter variable CITE to keep track of citation numbers. To create the assembled output in which the symbolic references are replaced by numeric ones, execute the UNIX commands in Fig. 2. These commands constitute a complete reference assembler for tags. The grep-awk pipe in the first three lines of Fig. 2 creates in the file sedscript a sequence of sed instructions that will associate the numbers 1 and 2 with the tags _Alice_ and _Huckleberry_, respectively. Invoked with this script, the sed command in the last line of Fig. 2 replaces all occurrences